<!DOCTYPE HTML>
<html lang="en">
<head>
<title>TrayTip - Syntax &amp; Usage | AutoHotkey</title>
<meta name="description" content="The TrayTip command creates a balloon message window near the tray icon. On Windows 10, a toast notification may be shown instead." />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<link href="../static/theme.css" rel="stylesheet" type="text/css" />
<script src="../static/content.js" type="text/javascript"></script>
</head>
<body>

<h1>TrayTip</h1>

<p>Creates a balloon message window near the tray icon. On Windows 10, a toast notification may be shown instead.</p>

<pre class="Syntax"><span class="func">TrayTip</span> <span class="optional">, Title, Text, Seconds, Options</span></pre>
<h2>Parameters</h2>
<dl>

  <dt>Title</dt>
  <dd>
    <p>The title of the window. Only the first 73 characters will be displayed.</p>
    <p>If <em>Title</em> is blank, the title line will be entirely omitted from the window, making it vertically shorter.</p>
    <p class="warning"><strong>Warning:</strong> The window will not be shown if the <em>Text</em> parameter is omitted, even if a <em>Title</em> is specified.</p>
  </dd>

  <dt>Text</dt>
  <dd>
    <p>The message to display. Only the first 265 characters will be displayed.</p>
    <p>If this parameter is omitted or blank, any TrayTip balloon window currently displayed will be removed. However, to hide a Windows 10 toast notification it may be necessary to <a href="#Windows10">temporarily remove the tray icon</a>.</p>
    <p>Carriage return (`r) or linefeed (`n) may be used to create multiple lines of text. For example: <code>Line1`nLine2</code>.</p>
    <p>If <em>Text</em> is long, it can be broken up into several shorter lines by means of a <a href="../Scripts.htm#continuation">continuation section</a>, which might improve readability and maintainability.</p>
  </dd>

  <dt>Seconds</dt>
  <dd><p class="note"><strong>Note:</strong> This parameter has no effect on Windows Vista and later.</p>
    <p>The approximate number of seconds to display the window, after which it will be automatically removed by the OS. Specifying a number less than 10 or greater than 30 will usually cause the minimum (10) or maximum (30) display time to be used instead. If blank or omitted, the minimum time will usually be used. This parameter can be an <a href="../Variables.htm#Expressions">expression</a>.</p>
    <p>The actual timeout may vary from the one specified. Microsoft explains, &quot;if the user does not appear to be using the computer, the system does not count this time towards the timeout.&quot; (Technical details <a href="https://msdn.microsoft.com/en-us/library/bb773352(VS.85).aspx">here</a>). Therefore, to have precise control over how long the TrayTip is displayed, use the <a href="Sleep.htm">Sleep</a> command followed by TrayTip with no parameters, or use <a href="SetTimer.htm">SetTimer</a> as illustrated in the Examples section below.</p>
    </dd>

  <dt>Options</dt>
  <dd><p>The <em>Options</em> parameter can be a combination (sum) of zero or more of the following values:</p>
    <table class="info">
      <tr><th>Function</th><th>Decimal Value</th><th>Hex Value</th></tr>
      <tr><td>Info icon</td><td>1</td><td>0x1</td></tr>
      <tr><td>Warning icon</td><td>2</td><td>0x2</td></tr>
      <tr><td>Error icon</td><td>3</td><td>0x3</td></tr>
      <tr><td>Windows XP and later: Do not play the notification sound.</td><td>16</td><td>0x10</td></tr>
      <tr><td>Windows Vista and later: Use the large version of the icon.</td><td>32</td><td>0x20</td></tr>
    </table>
    <p>If omitted, it defaults to 0, which is no icon. The icon is also not shown by the balloon window if it lacks a <em>Title</em> (this does not apply to Windows 10 toast notifications).</p>
    <p>This parameter can be an <a href="../Variables.htm#Expressions">expression</a>.</p>
    </dd>

</dl>
<h2>Remarks</h2>
<p>On Windows 10, a TrayTip window usually looks like this:</p>
<img src="../static/dlg_traytip.png" alt="TrayTip" />
<p id="Windows10"><strong>Windows 10</strong> replaces all balloon windows with toast notifications by default (this can be overridden via group policy). Calling TrayTip multiple times will usually cause multiple notifications to be placed in a "queue" instead of each notification replacing the last. To hide a notification, temporarily removing the tray icon may be effective. For example:</p>
<pre>TrayTip #1, This is TrayTip #1
Sleep 3000   <em>; Let it display for 3 seconds.</em>
HideTrayTip()
TrayTip #2, This is the second notification.
Sleep 3000

<em id="Hide">; Copy this function into your script to use it.</em>
HideTrayTip() {
    TrayTip  <em>; Attempt to hide it the normal way.</em>
    if SubStr(A_OSVersion,1,3) = "10." {
        Menu Tray, NoIcon
        Sleep 200  <em>; It may be necessary to adjust this sleep.</em>
        Menu Tray, Icon
    }
}
</pre>
<p>TrayTip has no effect if the script lacks a tray icon (via <a href="_NoTrayIcon.htm">#NoTrayIcon</a> or <code><a href="Menu.htm">Menu</a>, Tray, NoIcon</code>). TrayTip also has no effect if the following REG_DWORD value exists and has been set to 0:</p>
<pre>HKCU\Software\Microsoft\Windows\CurrentVersion\Explorer\Advanced &gt;&gt; EnableBalloonTips</pre>
<p>On a related note, there is a tooltip displayed whenever the user hovers the mouse over the script's tray icon. The contents of this tooltip can be changed via: <code><a href="Menu.htm">Menu</a>, Tray, Tip, My New Text</code>.</p>

<h2>Related</h2>
<p><a href="ToolTip.htm">ToolTip</a>, <a href="SetTimer.htm">SetTimer</a>, <a href="Menu.htm">Menu</a>, <a href="SplashTextOn.htm">SplashTextOn</a>, <a href="MsgBox.htm">MsgBox</a>, <a href="InputBox.htm">InputBox</a>, <a href="FileSelectFile.htm">FileSelectFile</a>, <a href="FileSelectFolder.htm">FileSelectFolder</a></p>

<h2>Examples</h2>
<div class="ex" id="ExBasic">
<p><a href="#ExBasic">#1</a></p>
<pre>TrayTip, My Title, Multiline`nText, 20, 17</pre>
</div>

<div class="ex" id="ExDisplayTime">
<p><a href="#ExDisplayTime">#2</a>: To have more precise control over the display time without having to use Sleep (which stops the current thread):</p>
<pre>#Persistent
TrayTip, Timed TrayTip, This will be displayed for 5 seconds.
SetTimer, HideTrayTip, -5000

HideTrayTip() {  <em>; NOTE: For Windows 10, replace this function with the one defined <a href="#Hide">above</a>.</em>
    TrayTip
}
</pre>
</div>

<div class="ex" id="ExPermanent">
<p><a href="#ExPermanent">#3</a>: To have a TrayTip permanently displayed, use a timer to refresh it periodically. NOTE: This probably won't work well on Windows 10 for <a href="#Windows10">reasons described above</a>.</p>
<pre>#Persistent
SetTimer, RefreshTrayTip, 1000
Gosub, RefreshTrayTip  <em>; Call it once to get it started right away.</em>
return

RefreshTrayTip:
TrayTip, Refreshed TrayTip, This is a more permanent TrayTip., , 16
return</pre>
</div>

</body>
</html>
